Walkthrough

The PR refreshes the OpenRTMP website with shared responsive styling, revised homepage and deployment content, four new guide routes, updated metadata and navigation, crawler files, documentation, and automated PHP, XML, and public-route checks.

Changes

OpenRTMP website refresh

Estimated code review effort: 3 (Moderate) | ~25 minutes

• Repositions the homepage, nav, footer, and download page around two audiences: library developers
 and self-hosted server operators.
• Adds a five-minute Docker + OBS quickstart and four SEO-focused guides (Docker self-hosting,
 RTMPS/OBS, Enhanced RTMP codecs, OpenRTMP vs nginx-rtmp).
• Adds canonical URLs, Open Graph/Twitter metadata, JSON-LD structured data, robots.txt, and
 sitemap.xml for search engines.
• Removes hard-coded release/version numbers in favor of registry/release links and a consistent
 alpha-status message.
• Adds a GitHub Actions workflow that lints PHP, validates the sitemap, and smoke-tests all public
 pages.
• Updates README to document the new site structure, content principles, and guide-authoring
 process.

graph TD
  H["includes/header.php"] --> IDX["index.php"]
  H --> QS["quickstart/index.php"]
  H --> GD["guides/*/index.php"]
  H --> DL["download/index.php"]
  F["includes/footer.php"] --> IDX
  F --> QS
  F --> GD
  SM[(sitemap.xml)] --> SEO[External Search Engines]
  RB[robots.txt] --> SEO
  CI[[Website checks CI]] --> IDX
  CI --> GD
  CI --> SM

  subgraph Legend
    direction LR
    _file["File"] ~~~ _db[(Data file)] ~~~ _ext[[CI Job]]
  end

Loading

For a static PHP marketing/documentation site, hand-authored PHP pages with shared header/footer includes and a lightweight CI smoke test are an appropriate, low-overhead approach. Introducing a static site generator or templating framework would add build complexity disproportionate to the site's size and update cadence.

Enhancement (5) +591 / -235

content.cssAdd stylesheet for guide, quickstart, and article content +287/-0

Add stylesheet for guide, quickstart, and article content

• New CSS file with styles for path cards, check lists, callouts, article/prose layout, TOC sidebar, FAQ items, guide cards, and comparison tables, including responsive breakpoints.

assets/css/content.css

index.phpSimplify download page and remove hard-coded version numbers +86/-126

Simplify download page and remove hard-coded version numbers

• Reworks the download page to lead with a Docker quickstart path and library path, replaces manually copied version strings with links to crates.io/GHCR, consolidates the Docker Compose/run examples, and adds SEO metadata fields.

download/index.php

footer.phpAlign footer navigation and messaging with ecosystem positioning +19/-20

Align footer navigation and messaging with ecosystem positioning

• Updates footer copy, navigation links, and badges to reflect the developer/operator positioning, adds links to quickstart and guides, and adds an alpha status note.

includes/footer.php

header.phpAdd SEO metadata, canonical URLs, and structured data support to header +28/-9

Add SEO metadata, canonical URLs, and structured data support to header

• Introduces default page title/description, canonical URL computation, Open Graph/Twitter meta tags, optional JSON-LD structured data output, escaped output via htmlspecialchars, and updated navigation links.

includes/header.php

index.phpReposition homepage around library and server audiences +171/-80

Reposition homepage around library and server audiences

• Rewrites the homepage hero, adds a dual-path section for developers vs operators, replaces the Rust code sample with a Docker quickstart preview, adds JSON-LD structured data, and reworks the features/architecture/ecosystem sections.

index.php

Documentation (6) +593 / -28

README.mdRewrite README to document ecosystem, structure, and guide-authoring process +45/-28

Rewrite README to document ecosystem, structure, and guide-authoring process

• Updates the README with the three-project ecosystem description, revised local dev port and validation instructions, new file structure listing including guides/quickstart, content principles, guide-authoring steps, and deployment notes.

README.md

index.phpAdd Enhanced RTMP HEVC/AV1/Opus guide +116/-0

Add Enhanced RTMP HEVC/AV1/Opus guide

• New SEO-focused technical guide explaining Enhanced RTMP signaling, FourCC codecs, capability negotiation, OpenRTMP implementation boundaries, and a codec interoperability test plan.

guides/enhanced-rtmp-hevc-av1-opus/index.php

index.phpAdd guides landing page +60/-0

Add guides landing page

• New landing page linking to the four new technical guides with tags, summaries, and a CTA toward the quickstart and docs.

guides/index.php

index.phpAdd OpenRTMP vs nginx-rtmp comparison guide +112/-0

Add OpenRTMP vs nginx-rtmp comparison guide

• New guide comparing OpenRTMP and nginx-rtmp across architecture, administration, statistics, and features, with migration considerations and coexistence guidance.

guides/openrtmp-vs-nginx-rtmp/index.php

index.phpAdd RTMPS server configuration guide for OBS +124/-0

Add RTMPS server configuration guide for OBS

• New guide covering enabling RTMPS alongside RTMP, certificate setup, server configuration, verification steps, OBS connection instructions, and troubleshooting.

guides/rtmps-server-obs/index.php

index.phpAdd self-hosted Docker RTMP server guide +136/-0

Add self-hosted Docker RTMP server guide

• New guide describing the Docker stack architecture, deployment steps, stream key model, OBS publishing, monitoring, production checklist, and troubleshooting.

guides/self-hosted-rtmp-server-docker/index.php

Other (4) +285 / -0

site-checks.ymlAdd CI workflow for PHP lint, sitemap validation, and page smoke tests +51/-0

Add CI workflow for PHP lint, sitemap validation, and page smoke tests

• New GitHub Actions workflow that lints all PHP files with php -l, validates sitemap.xml with xmllint, and curls every public page against a local PHP server on PRs and pushes to main.

.github/workflows/site-checks.yml

index.phpAdd five-minute Docker + OBS quickstart page +168/-0

Add five-minute Docker + OBS quickstart page

• New page with a HowTo JSON-LD schema guiding users through cloning the repo, generating secrets, starting the Docker stack, creating a stream, publishing from OBS, moving to production, and troubleshooting.

quickstart/index.php

robots.txtAdd robots.txt crawler policy +4/-0

Add robots.txt crawler policy

• New file allowing all crawlers and pointing to the sitemap.

robots.txt

sitemap.xmlAdd public sitemap.xml +62/-0

Add public sitemap.xml

• New XML sitemap listing all indexable public pages with change frequency and priority values.

sitemap.xml

Description

includes/header.php derives canonical URLs from $_SERVER['REQUEST_URI'] when $canonicalPath is
not set, so alternate paths like /docs/index.php can produce a different canonical than /docs/
for pages such as docs and legal. This can create duplicate canonicals/indexing fragmentation for
the same content depending on how the server routes requests.

Code

includes/header.php[R5-7]

+$canonicalPath = $canonicalPath ?? ($_SERVER['REQUEST_URI'] ?? '/');
+$canonicalPath = parse_url($canonicalPath, PHP_URL_PATH) ?: '/';
+$canonicalUrl = 'https://openrtmp.org' . $canonicalPath;

Evidence

includes/header.php uses $_SERVER['REQUEST_URI'] as the default canonical path and does not
strip directory index filenames. The docs/legal pages do not override $canonicalPath, so their
canonical depends on the exact URL used to reach them.

includes/header.php[1-8]
docs/index.php[1-6]
legal/index.php[1-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Some pages do not set `$canonicalPath`, so `includes/header.php` falls back to `$_SERVER['REQUEST_URI']` and uses its path verbatim. If the same page is reachable via both a directory URL and an `index.php` URL, the `<link rel="canonical">` will differ.

### Issue Context
- `docs/index.php` and `legal/index.php` currently don’t define `$canonicalPath`.
- `includes/header.php` builds `$canonicalUrl` directly from the (possibly unnormalized) request path.

### Fix Focus Areas
- includes/header.php[5-8]
- docs/index.php[1-6]
- legal/index.php[1-6]

### Recommended fix
Do one (or both):
1) Set `$canonicalPath` explicitly in pages that don’t set it today (e.g., `/docs/`, `/legal/`).
2) Add a small normalization step in `includes/header.php` after `parse_url(...)` to rewrite trailing `/index.php` to `/` (and ensure the path always starts with `/`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The nav toggle button is initialized with aria-expanded="false", but the click handler only
toggles a CSS class and never updates aria-expanded, leaving assistive technologies with stale
state after opening/closing the menu. This is an accessibility correctness regression introduced by
adding the ARIA attribute without syncing it in JS.

Code

includes/header.php[53]

+    <button class="nav-toggle" aria-label="Toggle navigation" aria-expanded="false">&#9776;</button>

Evidence

Markup declares an aria-expanded state, but the only toggle behavior in JS changes CSS classes, so
the ARIA state remains incorrect.

includes/header.php[36-55]
assets/js/main.js[10-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The navigation toggle button has `aria-expanded="false"`, but JavaScript never updates it when toggling the menu.

### Issue Context
`assets/js/main.js` toggles `.open` on the `.nav` container only.

### Fix Focus Areas
- includes/header.php[53-54]
- assets/js/main.js[10-18]

### Recommended fix
In `initNavToggle()`, after toggling `.open`, set:
- `const isOpen = nav.classList.contains('open');`
- `toggle.setAttribute('aria-expanded', String(isOpen));`
Optionally add `aria-controls` to the button and an `id` to the controlled element for stronger semantics.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

includes/header.php emits JSON-LD via json_encode(...) directly inside a <script> tag without
JSON_HEX_* escaping, so any future structured-data value containing </script> could break out of
the tag and inject HTML/JS. In this PR the values appear repo-controlled, so this is a
defense-in-depth hardening issue.

Code

includes/header.php[R30-32]

+<?php if (!empty($structuredData)): ?>
+<script type="application/ld+json"><?php echo json_encode($structuredData, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); ?></script>
+<?php endif; ?>

Evidence

The JSON-LD payload is inserted verbatim into a <script> element; without JSON_HEX_TAG (etc.),
certain substrings can terminate the script element in HTML parsing.

includes/header.php[27-32]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
JSON-LD is rendered inside a raw `<script>` element. Plain `json_encode` does not make the output safe for HTML script context (e.g., a literal `</script>` in a string can terminate the script element).

### Issue Context
Current structured data is hard-coded, but this becomes risky if structured data is ever composed from non-trusted sources (or even copied text that may include `</script>`).

### Fix Focus Areas
- includes/header.php[30-32]

### Recommended fix
Update the `json_encode` call to include HTML-safe escaping flags, e.g.:
- `JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE`
so `<`, `>`, `&`, quotes are escaped appropriately inside the script context.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The new CI smoke-test loop does not request /legal/ even though it is listed in sitemap.xml, so
regressions on that public page won’t be caught by the workflow. This reduces CI coverage relative
to the public pages declared for indexing.

Code

.github/workflows/site-checks.yml[R40-50]

+          for path in \
+            / \
+            /quickstart/ \
+            /guides/ \
+            /guides/self-hosted-rtmp-server-docker/ \
+            /guides/rtmps-server-obs/ \
+            /guides/enhanced-rtmp-hevc-av1-opus/ \
+            /guides/openrtmp-vs-nginx-rtmp/ \
+            /docs/ \
+            /download/; do
+            curl --fail --silent --show-error "http://127.0.0.1:8090${path}" >/dev/null

Evidence

The workflow enumerates paths to curl but omits /legal/, while the sitemap declares /legal/ as a
public URL.

.github/workflows/site-checks.yml[34-51]
sitemap.xml[57-61]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
CI smoke-test does not include the `/legal/` route.

### Issue Context
`sitemap.xml` includes `/legal/`, implying it is a public, indexable page.

### Fix Focus Areas
- .github/workflows/site-checks.yml[40-50]
- sitemap.xml[57-61]

### Recommended fix
Add `/legal/` to the list of paths in the smoke-test loop so it is checked like the other public pages.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools